8.3. Templates

Which reusable templates does this repository already ship?

Four kinds of template already live under .github/, and a derivative repository can copy them almost verbatim.

A template is a reusable starting point: it captures a proven structure once so the next project spends its effort on the new problem instead of rediscovering the same scaffolding.

This repository carries templates at two very different scales. At the small scale they are concrete and already shipped: the GitHub issue and pull-request forms under .github/ that shape every contribution before a maintainer reads it. At the large scale, "template" is a design decision you should make deliberately: whether to turn the whole reference agent into a parameterized project generator, or to fork it once and move on.

The three issue forms are structured GitHub forms, not free text. Each pins a title: prefix and labels: so triage is automatic, and required validations force the fields a maintainer actually needs.

The license field is what stops a proposal from smuggling in a paid feature gate. Two fields are invited but optional: the text-rendered log excerpt in bug.yml, and the suggested smallest unblocking change in docs.yml.

Three further templates complete the set:

1. Routing. config.yml sets blank_issues_enabled: false, so there is no unstructured escape hatch: every issue enters through a form. Its contact_links route vulnerabilities to a private security mailbox and readers to the rendered course, keeping exploit detail and "is this already fixed?" traffic out of the public tracker.
2. Pull-request template. PULL_REQUEST_TEMPLATE.md asks for What/Why/How and a Test Plan. Its checkboxes are the exact repository gate (mise run format, check, test, scan), plus "ran every changed documentation command from its documented working directory" and "added no credentials, generated reports, or unrelated changes."
3. Recurring maintenance template. docs-freshness.md is a checklist issue for re-verifying time-sensitive claims before each release. It covers model names such as qwen3:4b-instruct and gemini-3.6-flash, pinned versions such as agentgateway v1.4.1 and kagent 0.9.12, price targets, and measured checkpoints.

The reusable idea is not the wording but the shape: force structure at intake, label for automatic routing, make required fields carry the information a reviewer would otherwise chase, and close the unstructured escape hatch. What a contributor actually does with these forms is 8.5. Contributions.

Should you template or fork the reference agent?

Two honest paths exist for the whole agent, and most learners want the first.

1. Fork once. Start from the completed reference on main, branch, and change one boundary at a time while the gates stay green. This is exactly the path 8.7. Capstone endorses and grades. You keep the git history, the tests, and the infrastructure, and you pay no generator tax: the versions, migrations, and support a template owes every project it stamps out.
2. Extract a generator. Turn the reference into a parameterized template that stamps out many derivatives: separate repositories generated from one template. Do this only when several agents genuinely need the same packaging, validation, image, protocol, security, and delivery contracts. A generator is another product: it has its own versions, migrations, tests, and support obligations, and every parameter you expose is a promise to keep working.

main is a reference implementation, not a published project generator. If you have one derivative in mind, fork it. Reach for a generator only when maintaining it costs less than hand-porting the same changes into three or more repositories.

What should be parameterized?

Renaming this agent from "Ops Copilot" to "AgentOps Agent" touched OTEL_SERVICE_NAME, the MLflow experiment, the ADK app_name, the MCP server, and the audit actor. That list is the identity parameter.

In a generator a parameter is any value that legitimately differs between derivatives — identity, provider, ownership, and deployment coordinates — as opposed to structure that should stay fixed. Get this line wrong in either direction and the generator hurts: too few parameters and every derivative hand-edits the same files; too many and the template becomes a fragile configuration language.

For this agent the parameters group into:

1. Identity: the distribution/module name, the ADK app_name, the telemetry service name, the MLflow experiment and prompt-registry names, the audit actor, and the human-facing display name. The CHANGELOG's "Ops Copilot" → "AgentOps Agent" rename is a map of exactly which surfaces an identity change touches.
2. Model path: the provider, model id, and direct-or-gateway base URL.
3. Ownership: which tool, skill, and data packages ship, and who approves writes.
4. Serving: the advertised A2A address and the per-request call budget.
5. Deployment coordinates: the OCI image name, Kubernetes namespace, local registry, and the optional GCP project/region/zone/bucket.

Never template a credential, a personal path, an existing trace or runtime database, or a hard-coded cloud identity. That rule is already modelled in the reference:

1. .env.example ships only placeholders and is copied to a git-ignored .env; install, check, and test tasks never load it.
2. For the optional Ollama profile, OPENAI_API_KEY=local-ollama is a non-secret marker the OpenAI SDK requires and Ollama ignores — a real key never appears in the tree.
3. The GKE overlay mounts no cloud key at all. It uses Workload Identity Federation (WIF), a Kubernetes identity exchanged for a Google one, through iam.gke.io/gcp-service-account annotations (0.7. Glossary).

A generator inherits these patterns by copying .env.example (never .env), keeping the marker, and keeping WIF.

Where does each parameter live in this repository today?

Each parameter above lands in specific files. The table below is that map, one row per parameter.

What should remain invariant?

Parameterize identity and coordinates; freeze everything that makes the agent correct and operable. The point of a template is that its structure is trustworthy. Freeze:

1. the src/ package layout and the locked dependency workflow (uv sync --locked);
2. the one mise run task vocabulary that hooks, CI, and this course all reuse — see 8.5. Contributions and 8.4. Documentation;
3. the typed settings/domain/tool boundaries;
4. the immutable seed versus writable runtime state split (agents/data/incidents.db is never mutated);
5. direct local reads versus governed MCP reads and confirmed, audited writes;
6. offline branch-covered tests and deterministic adversarial cases;
7. the non-root image with explicit health, resource, storage, and NetworkPolicy declarations;
8. the docs/source synchronization contract and the OSS-boundary language that keeps optional cloud clearly labelled.

These are the same invariants the capstone must preserve; a generator simply refuses to make them parameters.

Which OSS templating tool should you use?

Pick Copier when generated projects must keep receiving template updates, Cookiecutter when a create-once scaffold is enough.

How do you validate a generated project?

You test the rendered project, not the template.

Generate into a disposable directory, run the reference's own gate against the output, then grep it for leftovers: unfilled template delimiters (the placeholder markers a generator replaces) and the source identity.

flowchart TD
  A[Parameterize] --> B[Render into a disposable directory]
  B --> C["mise run install / format / check / test / scan"]
  C --> D{Both overlays render and offline links pass?}
  D -- no --> A
  D -- yes --> E[Grep for leftover delimiters and source identity]
  E --> F{Any agentops-agent / agentops-open-course / INC-* leaks?}
  F -- yes --> A
  F -- no --> G[Usable without the original workspace: pass]

What proves this page worked?

Forking? You have nothing to prove here. Copy .github/ISSUE_TEMPLATE/ and .github/PULL_REQUEST_TEMPLATE.md into your own repository and move on.

Building a generator? Write the parameter table above and the expected generated tree, then prove that two different parameter sets both pass the complete gate from a clean checkout. Do not publish the generator until its update/migration behavior and license notices are themselves tested — a published generator promises those to every derivative.

This page owns the structure and enforcement of both scales. Three siblings carry the rest:

• 8.5. Contributions — the workflow that fills the forms in.
• 8.7. Capstone — the recommended way to build your own agent from this one.
• 8.4. Documentation — the docs contract those templates protect.

You are done when:

• Your own repository has the issue forms, a config.yml setting blank_issues_enabled: false, and a pull-request template whose checkboxes are your gate.
• You can say which path you are on, fork or generator, and name the cost you accepted.
• Generator path only: two different parameter sets each render a project that passes mise run install, format, check, test, and scan from a clean checkout.
• Generator path only: a grep of each rendered tree returns no agentops-agent, no agentops-open-course, and none of the reference domain (INC-*, its service names, its runbook slugs) — while agents/data/ carries the derivative's own seed and mise run check:data passes against it.

Return to 8. Community and pick your next maintenance question when you have decided, in one sentence, whether you are forking this repository once or maintaining a generator.